home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / aminet / biz / misc / imagefxdevkit.lha / doc / Loader.autodoc < prev    next >
Text File  |  1993-01-13  |  14KB  |  327 lines
  1. TABLE OF CONTENTS
  2.  
  3. loaders/LM_Load
  4. loaders/LM_LoadPalette
  5. loaders/LM_Signatures
  6. loaders/LM_CheckFile
  7.  
  8.  
  9. loaders/LM_Load                                          loaders/LM_Load
  10.  
  11.     NAME
  12.         LM_Load -- Load an image from disk.
  13.  
  14.     SYNOPSIS
  15.         buffer = LM_Load ( filename, id,  args )
  16.         D0.L               A0        D0.L A1
  17.  
  18.         struct Buffer *LM_Load ( char *filename, int id, LONG *args );
  19.  
  20.     FUNCTION
  21.         Attempts to load the given file as the format that this
  22.         loader module recognizes, translating it to 24-bit if
  23.         necessary.  Returns a valid Buffer structure which may
  24.         be directly used by ImageFX.
  25.  
  26.     INPUTS
  27.         filename    - filename of the image to load.
  28.  
  29.         id          - ID code, typically used to indicate which
  30.                       "flavor" of the file format we're trying to
  31.                       load.  This is passed unchanged from Montage
  32.                       from what was obtained through the
  33.                       LoadFormat structure ID field by
  34.                       LM_Signatures().  In most cases, this can
  35.                       be ignored.
  36.  
  37.         args        - Arguments from an Arexx command invocation.
  38.                       Most loaders will not need to worry about this,
  39.                       but it can be used to allow passing parameters
  40.                       to the loader via. Arexx commands.  Note that
  41.                       you must fill in the ModuleBase->CmdTable
  42.                       parameter for this to be valid.  See the
  43.                       example ANIM loading code for an example of
  44.                       using this argument.
  45.  
  46.     RESULT
  47.         buffer      - A valid Buffer structure, with the following
  48.                       fields filled in:
  49.  
  50.                         Name        - Filename passed to LM_Load().
  51.                         Type        - Short description of file type.
  52.                         Flags       - Set to 0.
  53.                         Width       - Width of buffer in pixels.
  54.                         Height      - Height of buffer in pixels.
  55.                         BitsPerPlane- Always 8.
  56.                         Depth       - Depth of buffer; 1 for grey, 3 for
  57.                                       color.
  58.                         Planes[]    - Pointers to either one or three
  59.                                       contiguous blocks of image data.
  60.                                       For a greyscale image this will
  61.                                       be a single plane of 8-bit
  62.                                       greyscale values; for a color image
  63.                                       this will be three planes of 8-bit
  64.                                       Red, Green, and Blue values.
  65.                         DPIX, DPIY  - Dots per inch horizontally and
  66.                                       vertically (if specified).
  67.                         PixAspectX,
  68.                         PixAspectY  - Pixel aspect ratio X and Y (if
  69.                                       specified).
  70.  
  71.                       You should use the function AllocBuffer() to
  72.                       allocate your Buffer structure, as this does
  73.                       a lot of necessary initialization from the arguments
  74.                       passed to it.
  75.  
  76.                       A NULL return indicates an error of some kind,
  77.                       with a more descriptive error code in the
  78.                       global error variable set with SetError().
  79.  
  80.     EXAMPLE
  81.  
  82.     NOTES
  83.         You should make the user aware of the size of the image you
  84.         are loading as soon as possible.  That is, as soon as you
  85.         find out the size of the image by reading the file, you
  86.         should call ShowStatus() to display that information to the
  87.         user while reading the rest of the file.
  88.  
  89.         Make sure this function gracefully handles disk errors.
  90.  
  91.         You should be aware that future versions of ImageFX may define a new
  92.         loader module vector that will take a pointer to an AmigaDOS file
  93.         handle instead of a filename.  It would not be a bad idea to organize
  94.         your code now such that the LM_Load() vector just opens the file and
  95.         passes control to a second function.  Like this:
  96.  
  97.             LM_LoadHandle (BPTR handle, int id, LONG *args)
  98.             {
  99.             }
  100.  
  101.             LM_Load (char *name, int id, LONG *args)
  102.             {
  103.                 BPTR handle;
  104.  
  105.                 if (handle = Open(name, MODE_OLDFILE)) {
  106.                     LM_LoadHandle(handle, id, args);
  107.                     Close(handle);
  108.                 }
  109.             }
  110.  
  111.  
  112.     BUGS
  113.  
  114.     SEE ALSO
  115.         loaders/LM_Signatures,scan/buf.h
  116.  
  117.  
  118. loaders/LM_LoadPalette                                    loaders/LM_LoadPalette
  119.  
  120.     NAME
  121.         LM_LoadPalette -- Read a color palette from an image file.
  122.  
  123.     SYNOPSIS
  124.         success = LM_LoadPalette ( filename, palette, id )
  125.         D0.L                       A0        A1       D0.L
  126.  
  127.         BOOL LM_LoadPalette ( char *filename, struct Palette *palette, int id );
  128.  
  129.     FUNCTION
  130.         Attempts to read a palette from the file given into the Palette
  131.         structure provided.  If this loader's file format does not support
  132.         a palette (a 24-bit format only), then an error should be returned.
  133.  
  134.     INPUTS
  135.         filename    - filename of the file to read a palette from.
  136.  
  137.         palette     - where to store the resulting palette read from
  138.                       the file.  The following fields in the Palette
  139.                       structure should be filled in:
  140.                            Depth - depth of palette in bitplanes.
  141.                                    Represents the minimum depth required
  142.                                    to store this palette.
  143.                            Count - number of entries in the palette.
  144.                                    Does not necessarily have to be
  145.                                    1 << Depth, but in most cases it
  146.                                    will be.
  147.                            Table - pointer to where to store the palette
  148.                                    entries themselves.  Each entry consists
  149.                                    of 8-bits each of Red, Green, and
  150.                                    Blue, in that order, so each palette
  151.                                    entry is 3-bytes long in this table.
  152.                                    If the palette is greyscale, then
  153.                                    equal values of red, green, and
  154.                                    blue must be stored.
  155.                            NumRanges - this indicates the maximum
  156.                                    number of ranges that the caller
  157.                                    can handle in his Palette structure.
  158.                                    Do NOT read more than this number
  159.                                    of ranges into the Palette structure!
  160.                            LowRange - pointer to array of where to store
  161.                                    the lower palette register of a range.
  162.                                    If the format you are loading does not
  163.                                    support color palette ranges, then you
  164.                                    should leave this alone.
  165.                            HighRange - pointer to array of where to store
  166.                                    the upper palette register of a range.
  167.                                    If the format you are loading does not
  168.                                    support color palette ranges, then you
  169.                                    should leave this alone.
  170.  
  171.         id          - ID code, typically used to indicate which
  172.                       "flavor" of the file format we're trying to
  173.                       load.  This is passed unchanged from ImageFX
  174.                       from what was obtained through the
  175.                       LoadFormat structure ID field by LM_Signatures().
  176.                       In most cases, this can be ignored.
  177.  
  178.     RESULT
  179.         success     - boolean success code, TRUE if successful, FALSE
  180.                       if something went wrong.  A further error code
  181.                       should be set with the SetError() function.
  182.  
  183.     EXAMPLE
  184.  
  185.     NOTES
  186.         Make sure this function gracefully handles disk errors.
  187.  
  188.     BUGS
  189.  
  190.     SEE ALSO
  191.       scan/loadsave.h
  192.  
  193.  
  194.  
  195. loaders/LM_Signatures                                  loaders/LM_Signatures
  196.  
  197.     NAME
  198.         LM_Signatures - Report the "signature" bytes to match for this
  199.                         file format.
  200.     SYNOPSIS
  201.         array = LM_Signatures ( );
  202.         D0.L
  203.  
  204.         struct LoadFormat *LM_Signatures ( void );
  205.  
  206.     FUNCTION
  207.         Reports to ImageFX the bytes that must be present in the
  208.         first bit of a file in order for it to be considered as the
  209.         format that this loader can handle.  Note that more than one
  210.         "signature" can be reported as different "flavors" of the file
  211.         format... for example, an ILBM loader could report that it can
  212.         handle a FORM ILBM or a FORM ANIM.
  213.  
  214.         Returning NULL indicates that you want to do custom file
  215.         identification, bypassing the normal (easy) file identification
  216.         used by simpler loaders.  If you want to do custom file
  217.         identification, you must supply the new function LM_CheckFile()
  218.         as described below.
  219.  
  220.     INPUTS
  221.         None.
  222.  
  223.     RESULT
  224.         array   - an array of LoadFormat structures, terminated with
  225.                   a structure with the Identifier field set to NULL.
  226.                   Each LoadFormat structure should be filled in as
  227.                   follows by the loader:
  228.  
  229.                     Identifier  - pointer to a string of bytes that
  230.                                   must be present at the beginning of
  231.                                   the file.  An identifier byte that is
  232.                                   the ASCII symbol "?" will match ANY
  233.                                   value in the input file.  Thus the
  234.                                   correct identifier string for an ILBM
  235.                                   loader would be "FORM????ILBM".  The
  236.                                   identifier string does NOT have to be
  237.                                   null-terminated.  Note:  if you need
  238.                                   to match an ASCII question mark in
  239.                                   the header, you're screwed.
  240.                     Length      - Number of bytes in the identifier
  241.                                   string.
  242.                     Name        - User-readable name of the format.
  243.                                   This is mainly for the "Load As"
  244.                                   function, to give the user a name
  245.                                   to pick.  It can also be used as
  246.                                   a method of selecting a file format
  247.                                   to load via. Arexx.  Avoid spaces
  248.                                   in this name.
  249.                     ID          - An ID strictly for the use of the
  250.                                   loader.  When a file matches the
  251.                                   identifier string, this ID value is
  252.                                   passed to the loader in the LM_Load()
  253.                                   call.  This can be used by the
  254.                                   loader to know which identifier was
  255.                                   matched if it can handle more than one.
  256.  
  257.                 A NULL return indicates you want to do custom
  258.                 file identification.
  259.  
  260.     EXAMPLE
  261.  
  262.         static struct LoadFormat loadformats[] = {
  263.            { "FORM????ILBM", 12, "IFF_Picture",   0 },
  264.            { "FORM????ANIM", 12, "IFF_Animation", 1 },
  265.            { NULL }
  266.         };
  267.  
  268.         struct LoadFormat *LM_Signatures (void)
  269.         {
  270.            return (loadformats);
  271.         }
  272.  
  273.     NOTES
  274.  
  275.     BUGS
  276.  
  277.     SEE ALSO
  278.         loader.library/LM_Load,loader.library/LM_CheckFile,scan/loadsave.h
  279.  
  280.  
  281.  
  282. loaders/LM_CheckFile                                       loaders/LM_CheckFile
  283.  
  284.     NAME
  285.         LM_CheckFile - Test to see whether a file is in the format
  286.                        expected by this loader, ie. custom file
  287.                        identification.
  288.  
  289.     SYNOPSIS
  290.         success = LM_CheckFile ( filename );
  291.         D0.L                     A0
  292.  
  293.         BOOL LM_CheckFile ( char *filename );
  294.  
  295.     FUNCTION
  296.         Checks the supplied file to see if it in the format recognized
  297.         by this loader.  Presumeably, checking for this type of file
  298.         requires more work than just matching the first few bytes in
  299.         the file.  You are given only the name of the file that Image
  300.         Scan is trying to load, you must open it yourself and read
  301.         whatever bytes are necessary to do the checking.
  302.  
  303.         You will need to use this method for any file format that does
  304.         not have an explicit "magic" constant at the beginning of the
  305.         file, but can still be identified by some pattern of bytes
  306.         somewhere within the file (ie. widths, heights, or whatever).
  307.  
  308.     INPUTS
  309.         filename - pointer to the name of the file to be checked.
  310.  
  311.     RESULT
  312.         success - Return TRUE if you recognize this file format and
  313.                   can load it.  (You can expect a call to your LM_Load()
  314.                   function soon after returning TRUE.)  Otherwise, return
  315.                   FALSE to allow ImageFX to continue checking the file
  316.                   with other loader modules.
  317.  
  318.     EXAMPLE
  319.  
  320.     NOTES
  321.  
  322.     BUGS
  323.  
  324.     SEE ALSO
  325.         loader.library/LM_Signatures,scan/loadsave.h
  326.  
  327.